import WebpackLicense from '@components/WebpackLicense';

<WebpackLicense from="https://webpack.docschina.org/configuration/watch/" />

# Watch

监听：该选项用于监听文件变更，并在变更时触发重新编译。

## watch

- **类型：** `boolean`
- **默认值：** `false`

开启监听模式，使 Rspack 在第一次构建完后不会退出，而是继续监听文件变更，并在变更时触发重新编译。

```js title="rspack.config.mjs"
export default {
  // ...
  watch: true,
};
```

:::tip
在使用 `@rspack/dev-server` 时，`watch` 默认为 true。
:::

## watchOptions

- **类型：** `object`

监听模式相关的配置项。

```js title="rspack.config.mjs"
export default {
  // ...
  watchOptions: {
    ignored: /node_modules/,
    poll: true,
  },
};
```

### watchOptions.aggregateTimeout

- **类型：** `number`
- **默认值：** `5`

当第一个文件更改后，在触发 rebuild 前存在一个延迟时间，Rspack 会将这段时间内进行的任何其他更改都聚合到一次 rebuild 里。你可以通过这个选项来设置这个时间，以毫秒为单位：

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    aggregateTimeout: 600,
  },
};
```

### watchOptions.ignored

- **类型：** `RegExp | string | string[]`
- **默认值：** `/[\\/](?:\.git|node_modules)[\\/]/`

监听时排除匹配到的路径。监听大量文件可能会导致 CPU 或内存使用率过高。

Rspack 从 v1.2.0 开始，默认排除 `node_modules` 和 `.git` 目录下的文件。这意味着当这些目录下的文件发生变化时，不会触发重新构建。

如果你希望监听 `node_modules` 目录，可以设置为仅排除 `.git` 目录：

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    ignored: /\.git/,
  },
};
```

`ignored` 可以使用 glob 匹配：

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    ignored: '**/.git',
  },
};
```

还可以使用多个 glob 匹配：

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    ignored: ['**/files/**/*.js', '**/.git', '**/node_modules'],
  },
};
```

还可以指定为一个或多个绝对路径：

```js title="rspack.config.mjs"
import path from 'node:path';

export default {
  //...
  watchOptions: {
    ignored: [path.posix.resolve(__dirname, './ignored-dir')],
  },
};
```

当使用 glob 匹配时，Rspack 会将它们转换为正则表达式，因此在使用 glob 匹配之前，请确保你熟悉 [glob-to-regexp](https://github.com/fitzgen/glob-to-regexp)。

### watchOptions.poll

- **类型：** `boolean`, `number`
- **默认值：** `false`

是否通过轮询进行监听。

当设置为 `true` 时，默认的轮询间隔为 5007 毫秒。

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    poll: true,
  },
};
```

还可以设置一个自定义的轮询间隔：

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    poll: 1000, // 每秒检查一次
  },
};
```

### watchOptions.followSymlinks

- **类型：** `boolean`
- **默认值：** `false`

是否根据软链接查找文件。这通常是不需要的，因为 Rspack 已经使用 [resolve.symlinks](/config/resolve#resolvesymlinks) 解析了软链接。

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    followSymlinks: true,
  },
};
```

### watchOptions.stdin

- **类型：** `boolean`

当 stdin 流结束时停止监听。

```js title="rspack.config.mjs"
export default {
  //...
  watchOptions: {
    stdin: true,
  },
};
```
